「好的註解讓你讓天堂，差的註解讓你淚兩行」這是我們看程式時，最佳的心情寫照。

註解的重要性可見一般。只是，什麼時候要註解？註解的內容又要有哪些呢？

我們先來看一下書中舉的一個極端的例子：

'*****************************************************************
'* 常式名稱：CopyString
'*   
'* 目的：這個常式從來源字串(Source$)複製字串到目的字串(Target$)
'*
'* 演算法：首先取得 Source$ 的長度，然後每次複製一個字元到 Target$。
'*         它使用迴圈索引值當做存取陣列時的索引值來存取 Source$ 與
'*         Target$ 內的資料，並且在複製完一個字元後遞增索引值。
'*
'* 輸入資料：Inputs$ 要複製的字串
'*
'* 輸出資料：Outpur$ 準備接收複製資料的字串
'*
'* 預設條件：無
'*
'* 程式修改記錄：無
'*
'* 作者：黃小暐
'* 撰寫日期：10/1/92
'* 電話：(222) 555-2255
'* 
'*****************************************************************

如果您看到這種註解，是不是當場傻眼！這樣好像只要閱讀註解就可以知道這個常式在做什麼，很詳細也很清楚！但是這樣到底是寫程式為主還是寫註解為主？

因為我們在閱讀程式的過程中，其實就會了解這段程式所執行的方式，其實是不需要個別去說明的。（這反倒是比較像系統設計文件所撰寫的東西）每次有異動，就會一直累計資料，註解不斷的長大，反倒有點宣賓奪主的味道了。與其這樣，倒不如用 Blog 來記錄開發的過程，查詢也比較方便。

在前面已經介紹了很多程式撰寫時方便閱讀與維護的技巧，程式即是註解，其實就是最高的境界了。但是總是有不足之處，例如是什麼時候修改的？是為了什麼目的修改的？

所以，如果註解能夠扮演著畫龍點睛之妙，則是最佳的模式了。
那麼我們應該怎樣來進行註解？

.宣告的註解
.說明數值資料的單位
.資料所允許的數值範圍
.輸入的條件限制
.為全域變數的功用加註

.標示程式區塊的開始與結束
最常看到的就是 HTML 原始碼中常會出現的標示了。在一般的程式設計中，反倒是比較少這樣做，大部分都只有開頭的註解做區隔而已。

.維護程式時的註記
養成良好的習慣，將維護記錄寫在所修改的程式上方，註記日期、修改者、需求者，甚至如果有需求單的編號，並說明修改的目的，解決的問題。

.著重在「為什麼？」而不是「如何做」
就像一開頭的註解的例子，我們不需要在註解中說明這段程式是如何撰寫的，而是要說明撰寫這段程式碼的目的。

.將註解靠近所需說明的程式
如果我們將註解都像文章開頭一樣，都寫在巨大的註解區塊中，要去了解程式的來龍去脈是會有點困難與花時間的。

其他一些也常會使用的註解方式，羅列如下：
**.在常式的開頭用一、二句話說明常式的功用

[b].說明常式的預設條件**

.保留常式的修改過程

.將註解跟隨程式縮排
保持一貫的程式撰寫風格，即使是註解，也讓他跟著程式一起進行縮排，視覺上會比較美觀有秩序。（一般的開發工具，對於註解是不會自動幫您縮排的）

.以至少一行空白行來區隔註解與程式段落

很多時候，我們會引用網路上的 Open Source 撰寫的程式碼，我們常會發現有以下的註解：

.簡述個別檔案或常式的目的
.作者簡介及聯絡資訊
.版權聲明及授權方式

在引用的時候，為尊重原作者，盡可能將作者的註解一併置入程式中，更好的是，通知作者引用其程式碼，並致感謝之意。

而有些授權方式，是您也要將所修改後的原始碼 Open 出去，這點可能要多留意一下。

本系列文章